Related Issues

• part of https://github.com/deepset-ai/haystack-private/issues/329

Proposed Changes:

Before trying to restrict a SearchableToolset to a subset of its catalog by name at Agent runtime did not work:

from typing import Annotated

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import SearchableToolset, tool

@tool
def get_weather(city: Annotated[str, "The city to look up"]) -> str:
    """Get the current weather for a city."""
    return f"It's sunny in {city}."

@tool
def get_stock_price(symbol: Annotated[str, "The ticker symbol, e.g. 'AAPL'"]) -> str:
    """Get the latest stock price for a ticker symbol."""
    return f"{symbol}: $123.45"

@tool
def search_news(query: Annotated[str, "What to search for"]) -> str:
    """Search recent news headlines."""
    return f"Top story for '{query}': ..."

# We set search_threshold=2 so SearchableToolset is put into search mode.
toolset = SearchableToolset(catalog=[get_weather, get_stock_price, search_news], search_threshold=2)
agent = Agent(chat_generator=OpenAIChatGenerator(), tools=toolset)

# We restrict this run to only use get_weather and get_stock_price
result = agent.run(
    messages=[ChatMessage.from_user("What's the weather in Milan and the price of AAPL?")],
    tools=["get_weather", "get_stock_price"],
)

Before:

• the call raised ValueError: The following tool names are not valid: {'get_weather', 'get_stock_price'}. Valid tool names are: {'search_tools'}
• Previously SearchableToolset only exposed its search_tools bootstrap tool (not its catalog) when flattened, so catalog tools couldn't be selected by name.
• And passing tools=["search_tools"] instead would have collapsed the toolset into a single item list of just search_tools which disabled discovery.

After: the SearchableToolset is kept intact, and when a user restricts the tools to get_weather and get_stock_price search and lazy-loading still work over the restricted subset.

How this is fixed: instead of flattening the toolset into a static list of tools, the Agent now keeps the Toolset intact and applies the name selection to it:

1. Validation against the full catalog. Requested names are validated against Toolset.get_selectable_tools(). SearchableToolset overrides this to return its entire catalog, so catalog tools are now resolvable by name (previously only its search_tools tool was, since iterating the toolset only exposes that bootstrap tool plus already-discovered tools).
2. The toolset stays live. Rather than replacing the toolset with a static list[Tool], the Agent registers the requested names as a per-run selection on the live Toolset (via Toolset._selected_tool_names) and keeps that object as the run's tools.
3. Iteration honors the selection. When the Agent re-reads its tools each step, the Toolset yields only the selected tools. For SearchableToolset this means the search_tools tool is still exposed and search/discovery is restricted to the selected catalog tools — so search and lazy-loading keep working over the subset instead of being disabled.

Changes Made:

• Toolset gained two methods: get_selectable_tools() returns every tool available for name-based
  selection (ignoring any active selection restriction, e.g. the one used by SearchableToolset), and
  spawn().
• SearchableToolset now exposes its full catalog of tools via SearchableToolset.get_selectable_tools().
• Runtime tool-name selection via Agent.run(tools=["tool_a", "tool_b"]) now resolves correctly when a
  SearchableToolset is configured. Previously the SearchableToolset was flattened into a single-item
  list (just its search tool), which broke its search and lazy-loading behavior.

How did you test it?

New tests

Notes for the reviewer

I did check locally that these changes work with our existing MCPToolset integration without any need for changes there.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.